API Design Pattern of the Week 19: Public API
A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”
The first 14 patterns in this “API Design Pattern of the Week” series came as LinkedIn articles; patterns 15 to 21 are Medium stories. All API Design Patterns of the Week are listed in this index and overview story.
Note: This online excerpt of the pattern predates its final version in the book.
Context
A system wants to provide a remote API that exposes one or more API endpoints. The API clients that are supposed to reach this API reside in different organizations, possibly even in different countries. They might or might not be known to the provider.
Problem
How can an API be made available to an unlimited and/or unknown number of API clients outside the organization that are globally, nationally, and/or regionally distributed?
Forces
The required level of API visibility is determined by the hosting location and its network connections (e.g., the Internet, an extranet, or a company-internal network or even a single data center). Criteria include:
- Business model
- Target audience size, location, and diversity
- Complexity and maturity of required backend systems and data stores
- Security considerations
- Budgets (development and operations, maintenance and evolution)
Solution Sketch
Expose the API on the public Internet along with a detailed API Description that describes both functional and nonfunctional properties of the API.
An illustration of the Public API pattern is:
The other visibility levels that we captured as patterns are Community API and Solution-Internal API (see Foundations category overview for links).
Forces
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
See pattern coverage on our website.
Related Patterns
A Public API either supports Frontend Integration or Backend Integration scenarios and stories. This pattern is also known as Open API; however, a truly open API is a Public API without an API Key or other authentication means). The Public Cloud pattern in (Fehling et al. 2014) has a similar context and intent, but is more concerned about IT infrastructure.
Two other patterns modeling visibility levels are Community API and Solution-Internal API. The pattern can be combined with Backends For Frontends as described by Sam Newman.
References
Fehling, Christoph, Frank Leymann, Ralph Retter, Walter Schupeck, and Peter Arbitter. 2014. Cloud Computing Patterns: Fundamentals to Design, Build, and Manage Cloud Applications. Springer.
Newman, Sam. 2015. Pattern: Backends For Frontends. Single-purpose Edge Services for UIs and external parties. Online (last accessed Nov 27, 2023).
Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.
This pattern originally appeared on our website https://api-patterns.org, which collects 44 patterns in five categories: : Foundation, Structure, Responsibility, Quality, Evolution.
Copyright © 2019–2023 by the authors. All rights reserved.
See terms and conditions of use.
